监控传统服务器和应用_使用OneAgent定制探针版本

最后于 2024年9月10日 更新

APO 分为两部分：

APO-server： APO 服务侧组件
APO-one-agent： APO 用户侧组件，用于采集Kubernetes集群或者虚机环境下被监控业务以及集群、主机信息。

本文档包含配置 APO-one-agent 自定义 Java 探针，并在传统服务器（非Kubernetes）上安装和运行定制版镜像 APO-one-agent 的说明。请确保在安装 APO-one-agent 之前，您已经安装 APO-server。

注意： 如果您想安装默认探针版本的 APO-one-agent ，可以根据监控传统服务器和应用_使用OneAgent默认OTEL探针版本

APO-one-agent 内置各个编程语言的默认采集探针版本：

Java agent: opentelemetry-java-instrumentation v2.5.0
Python agent: opentelemetry-python 1.23.0/0.44b0
NodeJs agent: opentelemetry-js v1.24.1/0.51.1
Go agent: opentelemetry-go-instrumentation v0.13.0-alpha

注意： 目前只推荐使用 Skywalking 或者 OpenTelemetry 的 Java 探针；暂不支持除 Java 以外的语言的探针替换。

如何替换 APO-one-agent 中的 Java 探针

针对 Java 应用，APO-one-agent 默认集成了以下版本 Java 探针：

Opentelemetry v2.5.0（默认）

本文档介绍如何在安装 APO-one-agent 时使用其他 Java 探针版本。

如果默认集成的探针版本不满足你的需求，参考下面的步骤构建自定义的 APO-one-agent 中的探针镜像；这样你可以使用比如 Skywalking v9.2.0 或 Opentelemetry v2.2.0 之类的其他版本探针。

1. 下载 OneAgent builder 模版

下载地址: https://apo-ce.oss-cn-hangzhou.aliyuncs.com/preload-builder.zip

模版的文件目录结构如下：

preload-builder
├── opentelemetry-java
│   ├── Dockerfile
│   ├── libapoinstrument.conf
│   └── opentelemetry
│       └── opentelemetry-javaagent.jar
└── skywalking-java
    ├── Dockerfile
    ├── libapoinstrument.conf
    └── skywalking-agent
        ├── ...
        └── skywalking-agent.jar

2. 替换探针文件

注意: 你只需要替换自己需要的探针,不需要同时替换OTEL和Skywalking的探针

OTEL探针

OTEL的JAVA探针以单个Jar包的方式提供。

使用需要的版本的OTEL探针替换模版目录中的 opentelemetry-java/opentelemetry/opentelemetry-javaagent.jar 文件, 注意不要更改文件名。

Skywalking探针

从Skywalking官网获得的探针文件通常是一个包含有 skywalking-agent.jar 和其配置文件的文件夹;

推荐的做法是移除模版中的 skywalking-java/skywalking-agent 目录, 随后用官网下载的探针文件进行替换;

这是因为不同版本的 skywalking-agent.jar 和其他文件可能不兼容, 完整替换是最安全的。

注意替换后不要更改skywalking-java/skywalking-agent/skywalking-agent.jar的文件名.

3. 构建镜像

如果使用的是自定义的OTEL探针

使用下面的脚本来进行探针构建

cd opentelemetry-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

如果使用的是自定义的Skywalking探针

使用下面的脚本来进行探针构建

cd skywalking-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

4. 同步镜像文件到机器

你需要将构建好的镜像文件推送到可用的Harbor仓库,或者手动同步到机器.

推送到Harbor仓库(注意将脚本中的HARBOR_REGISTRY修改为仓库地址)

HARBOR_REGISTRY=#修改为仓库地址

docker tag registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom
docker push $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom

手动同步到机器

docker save registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom | gzip > apo-odiglet.tgz

将生成的文件复制到后续部署探针的机器上(如果是K8s环境需要复制到每个节点上) 在每个节点上执行下面的命令加载镜像

gunzip -c apo-odiglet.tgz | docker load

5. 安装时使用新构建的镜像

完成上面的镜像推送步骤,你会获得一个可用的探针镜像版本:

如果你使用Harbor,后续使用$HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom, 注意$HARBOR_REGISTRY修改为你的仓库地址
如果你是手动推送的,后续使用 registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom

准备安装工作

这里默认下载 latest 版本安装包，本文档接下来以 latest 版本为例

export APO_VERSION=latest
# export APO_VERSION=v0.0.000 # 可以指定您的版本

wget https://apo-ce.oss-cn-hangzhou.aliyuncs.com/apo-one-agent-compose-${APO_VERSION}.tgz

部署 APO-one-agent

安装 APO-one-agent 时,使用下面的参数以指定使用您的自定义版本镜像：

export APO_VERSION=latest
export APO_SERVER_IP=<YOUR APO-server NodeIP> # FIXME
# 增加两个环境变量配置
export JAVA_AGENT_TYPE="OTHERVERSIONS-SW" # 如果您使用Skywalking的Java探针
# export JAVA_AGENT_TYPE="OTHERVERSIONS-OTEL" # 如果您使用Opentelemetry的Java探针
export APO_ODIGLET_IMAGE="你的自定义 APO-one-agnet 镜像全名" # FIXME

tar -zxvf apo-one-agent-compose-$APO_VERSION.tgz
cd apo-one-agent-compose/
bash deploy.sh init $APO_SERVER_IP

验证

见到类似输出即代表安装成功

==================================================
      ___           ___           ___
     /\  \         /\  \         /\  \
    /::\  \       /::\  \       /::\  \
   /:/\:\  \     /:/\:\  \     /:/\:\  \
  /::\~\:\  \   /::\~\:\  \   /:/  \:\  \
 /:/\:\ \:\__\ /:/\:\ \:\__\ /:/__/ \:\__\
 \/__\:\/:/  / \/__\:\/:/  / \:\  \ /:/  /
      \::/  /       \::/  /   \:\  /:/  /
      /:/  /         \/__/     \:\/:/  /
     /:/  /                     \::/  /
     \/__/                       \/__/
Official Website:   https://apo.kindlingx.com/
DEPLOY_VERSION: <version>
APO_ONE_AGENT_VERSION:
==================================================
INFO: APO-server-ip = <YOUR APO-server NodeIP>
 Container apo-otel-collector-agent  Started
 Container apo-grafana-alloy  Started
 Container apo-node-agent  Started
 Container apo-preload-agent  Started
 Container apo-go-sdk-auto  Started
 Container apo-ilogtail  Started
 Container apo-ebpf-agent  Started

输入下方命令检查容器是否启动成功

bash deploy.sh list

# 您应该看到类似于以下内容输出
NAME                 IMAGE                                                                 COMMAND                   SERVICE              CREATED          STATUS          PORTS
apo-ebpf-agent       registry.cn-hangzhou.aliyuncs.com/originx/ebpf-agent:v1.5.0           "sh start.sh"             apo-ebpf-agent       5 minutes ago   Up 5 minutes
apo-go-sdk-auto      registry.cn-hangzhou.aliyuncs.com/originx/sdk-auto:v1.0.0             "/app/originx-sdk-au…"   apo-go-sdk-auto      5 minutes ago   Up 5 minutes
apo-grafana-alloy    registry.cn-hangzhou.aliyuncs.com/originx/grafana-alloy:v1.2.1        "/bin/alloy run --st…"   apo-grafana-alloy    5 minutes ago   Up 5 minutes
apo-ilogtail         registry.cn-hangzhou.aliyuncs.com/originx/ilogtail:v1.5.0             "/usr/local/ilogtail…"   apo-ilogtail         5 minutes ago   Up 5 minutes
apo-node-agent       registry.cn-hangzhou.aliyuncs.com/originx/node-agent:v1.5.0           "/app/pinger"             apo-node-agent       5 minutes ago   Up 5 minutes
apo-otel-collector   registry.cn-hangzhou.aliyuncs.com/originx/apo-otel-collector:v0.1.0   "./otelcol --config …"   apo-otel-collector-agent   5 minutes ago   Up 5 minutes

重启被监控应用

非容器应用 重启应用即可自动监控应用。 Docker 容器应用 APO-one-agent 确认启动完成后，需要根据《在Docker容器内使用one-agent》配置并重启 Docker 应用。

卸载 APO-one-agent

bash deploy.sh stop

探针配置变更(高级功能)

注意: 如果你没有修改配置的需求,可以跳过这一部分. APO和提供的模版已经配置好了基础参数.

在大多数时候,你不需要考虑探针的配置问题, preload通过一定的逻辑为探针配置了必须的两个参数:

服务名 (OTEL_SERVICE_NAME/SW_AGENT_NAME): 由 jar 包或主类名生成
数据发送地址 (OTEL_EXPORTER_OTLP_ENDPOINT/ SW_AGENT_COLLECTOR_BACKEND_SERVICES): 由 apo 的部署文件进行维护

其余参数均使用探针的自身的默认配置

如果需要修改默认参数, 可以参考下面的内容修改模版中对应的libapoinstrument.conf文件以下面的示例模版为例, 每个模版中包含三个文件或目录, 其中AAAA/BBBB都是泛指,即不限定文件名:

Dockerfile: 决定了要更新preload-agent镜像中的哪些文件,通常不需要修改
libapoinstrument.conf: 决定了使用探针时的配置
BBBB目录: 包含自定义探针的可执行文件和自带配置

preload-builder
└── AAAA
    ├── Dockerfile
    ├── libapoinstrument.conf
    └── BBBB
        └── CCCC.jar

构建镜像时

AAAA目录下的所有文件将被复制到镜像的/etc/apo/instrumentations/custom/目录下;
libapoinstrument.conf中的所有配置会替换镜像中已有的配置.

libapoinstrument.conf 配置说明

以 opentelemetry 的配置为例, 模版中的的配置文件如下:

[java]
OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}
OTEL_EXPORTER_OTLP_ENDPOINT= {{APO_COLLECTOR_GRPC_ENDPOINT}}
JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
JAVA_OPTS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_TRACES_SAMPLER=always_on
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

下面是配置的说明:

[java] 作为一小节的开头,标识本节的所有配置作为java程序启动时自动注入的环境变量; 目前支持 java/python/nodejs/dotnet 四种语言
OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}, 因为服务名信息需要在应用启动时动态生成,所以使用APO提供的动态变量{{APO_AUTO_SERVICE_NAME}}来替换.可用的动态参数如下
- APO_AUTO_SERVICE_NAME: 自动发现服务名,目前仅支持JAVA,python/nodejs/dotnet会用对应的语言名作为APO_AUTO_SERVICE_NAME
- APO_COLLECTOR_GRPC_ENDPOINT APO的OtelCollector地址,接收otlp协议数据
- APO_COLLECTOR_HTTP_ENDPOINT 同上,接收otlphttp协议数据
- APO_COLLECTOR_SKYWALKING_ENDPOINT 同上,接收skywalking协议数据
JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/BBBB/CCCC.jar, 因为模版目录下的文件全部会复制到镜像的/etc/apo/instrumentations/custom/目录下,所以用这个绝对路径来指定探针的文件
其他参数为静态参数,将直接作为环境变量添加到程序启动, 下面的文档提供了如何使用环境变量设置探针参数

OTEL的自定义配置参考下面的文档 Configuration

Skywalking的自定义配置参考下面的文档 Setting Override

如何替换 APO-one-agent 中的 Java 探针​

1. 下载 OneAgent builder 模版​

2. 替换探针文件​

OTEL探针​

Skywalking探针​

3. 构建镜像​

如果使用的是自定义的OTEL探针​

如果使用的是自定义的Skywalking探针​

4. 同步镜像文件到机器​

5. 安装时使用新构建的镜像​

准备安装工作​

部署 APO-one-agent​

验证​

重启被监控应用​

卸载 APO-one-agent​

探针配置变更(高级功能)​

libapoinstrument.conf 配置说明​